PC Media 3

home *** CD-ROM | disk | FTP | other *** search

/ PC Media 3 / PC MEDIA CD03.iso / share / os2 / v2_614 / vc7 < prev next >

Wrap

Text File | 1993-12-16 | 31.7 KB | 643 lines

.TOPIC: Customizing VBBS VBBS 6.12 Documentation -- 7-1 ╔════════════════════════════════════════════════════════════════╗ ║ CHAPTER SEVEN CUSTOMIZING VBBS ║ ╚════════════════════════════════════════════════════════════════╝ The configurability of VBBS can not be overstated. Because of the way VBBS is structured, it's possible to configure the program to look and feel like some other BBS soft- ware; you can borrow features from several different BBS soft- wares to create your own design. You might just take a vacation from reality one night and decide to make VBBS look just like GEnie or some other CIS. Aside from the obvious limitations on actual storage space, you could accomplish the "look-alike" to the point where a user could not tell the difference! By using scripts (and the source code, if you've registered for it), you can do many things that simply aren't possible with other BBS softwares. Unlike source code, which normally contains strict rules on code segment distribution (VBBS included), VSCRIPT-based ap- lications, function blocks, and menus may be distributed freely in full, or even in entire configuration sets. Menus, Function Blocks, Scripts, and Mods ═════════════════════════════════════════ Customization and modification of VBBS comes in several forms: changing the menus to suit your personal tastes and set- up, rearranging function-block commands, installing scripts for special applications, and even modifying the source code (if you've registered at the source level). Menus and function blocks are closely interrelated, so if you find yourself flipping back and forth between the sec- tions on the two, don't worry; it's normal. For the remainder of this manual, the term "script" will apply exclusively to programs utilizing the VSCRIPT script lan- guage; the term "mod" will refer exclusively to modifications made at the source-code level. It should be pointed out here that you do not need to register VBBS to write scripts or ex- change scripts with other sysops via VirtualNET; registration and an additional fee ARE, however, required to obtain the VBBS source code. There are other good reasons to register VBBS; we'll get to those presently. "Heart-Code ANSI" ═════════════════ If you've read this far, you've run across the term "heart-code ANSI" a time or two. Since customization often in- volves changing colors and menus and adding system taglines, this is probably a good place to explain what "heart-code ANSI" is. VBBS 6.12 Documentation -- 7-2 If you've ever used the DOS "type" command to look at a file you've created using TheDraw or some other ANSI drawing program, you know it consists mainly of "garbage" resembling Chinese. This is the ANSI (American National Standards Institute) code for introducing color changes into text files so that the colors will show up onscreen; in order to display these color changes, you need to have the statement DEVICE=ANSI.SYS somewhere in your CONFIG.SYS file (remember, though, about the ANSI bomb -- see "First-Time Startup" for details on alternate ANSI drivers). A while back, a good number of BBS programs began using a method of color changing called "heart-code ANSI", in which color changes were represented by a heart character followed by an alphanumeric character. The heart-code system has the benefit of taking only two bytes to accomplish what takes 4-6 bytes in "raw" ANSI, thereby reducing the size of network transfers, especially where large numbers of color changes are involved. In an effort to maintain compatibility other bulletin board networks, VBBS was designed to handle heart-code ANSI. The heart-code colorization system has become the stan- dard for these BBS softwares. When you're starting out with heart-code ANSI, it's a good idea to go into the VBBS FSE and press [Ctrl-P][?], and look at the color combinations that appear at the bottom of the screen. The same set of color combinations can be seen when you go into your [D]efaults setup and start changing your screen display colors; you might consider printing out that screen using [Shift-Print Screen]. --> IMPORTANT NOTE: If you print-screen the default-menu color change information, be aware that all the codes are "off" by one; for exam- ple, the screen code for gray on black is 1, but the heart-code for gray on black is 0 (zero). Likewise, the bright-red on black is screen code 7, but heart-code 6. ╔═╗ Using heart-code ANSI takes some getting used to, but ╚═╝ with practice, it's not terribly more difficult than the "raw" ANSI produced by TheDraw or other ANSI draw programs. Heart-code ANSI is best for menus, taglines, and other features that have patterned or infrequent color changes. VBBS 6.12 Documentation -- 7-3 The easiest way to produce a heart-code menu or tagline is to first use an ANSI drawing program to make the menu/tag- line, then save it as a straight ASCII text file. Then, pull it into the VBBS FSE and use [Ctrl-P] codes to change the co- lors (see Appendix C for details). To introduce a heart-code color change into an ASCII text file, turn Num Lock ON; while holding down the [Alt] key, type in either "3" or "259" (whichever works) FROM THE NUMERIC KEYPAD. A heart character should appear on your screen. The second keystroke should be a number from 0-9 or a letter from A-Z, depending on what color you want to produce. Customizing Menus ═════════════════ The VBBS archive includes a default set of function blocks (see below) and their accompanying menus. After running the de- faults for a while, however, most sysops want to customize their menus to more accurately reflect their personal tastes and give their BBS a distinctive look. Default VBBS has four different types of menu files: .MNU files (the default) .ANS and .ASC files .PDM files We'll take a moment to explain each one in detail (there is one more menufile type if your BBS is set up to use the R.I.P. (Remote Imaging Protocol). On startup, VBBS looks for menu files with the .MNU ex- tension. The .MNU files included with VBBS are done in heart- code ANSI, and serve "double duty". If the user's video display will support ANSI graphics, the color changes will be included, but if it won't (user's defaults set to ASCII), VBBS will strip out the color changes for display to that user. The main bene- fit of this system is that by using the heart-code .MNU files, only one set of menu files is needed for both ANSI and ASCII users. Another point in favor of the .MNU files is that they seem to display a little bit faster -- this is probably due to the fact that it takes only two bytes to make a color change. The second set of menu formats -- .ANS and .ASC files -- is what VBBS will look for if it doesn't find .MNU files. The .ANS format is "raw" ANSI, such as that produced by TheDraw; an .ASC extension represents an ASCII (text) menu. The advan- tages to having these files in lieu of .MNU files is that they VBBS 6.12 Documentation -- 7-4 1) are a little bit quicker to produce, i.e., you draw a menu directly in ANSI, save it twice (in .ANS format and in .ASC format), and you're done. 2) are easier to make, especially if you have very com- plex menus and color changes; the heart-code system can be a little daunting if your menus are ornate. The downside of this method is that you must have two copies of each menu, one for ANSI users and one for ASCII users; if a user with ASCII defaults gets an .ANS menu, he/she will receive gar- bage characters (as shown above) and probably won't call back. The final set of files are VBBS' "pull-down" menus, which have a .PDM extension. These are for users who have selected "Enhanced ANSI" as their screen display default. These are ac- tually ASCII text files that VBBS colorizes as part of the de- fault color selection. A user may opt to use .PDMs at any sys- tem prompt by pressing the [Esc] key -- and you should try it to see how they work. The default FILES.PDM file is shown below: Directory C Change Directory [C] L List Files [L] S Search All Dirs [S] N New Files List [N] F Find Description [F] Transfer D Download Files [D] U Upload Files [U] B Batch Functions [B] R Review Files [R] Y Your Stats [Y] Other J New File Scandate [J] P Popular Downloads [P] M Download Master List [M] Q Quit to Main Menu [Q] G Log Off [G] These files are preconfigured, but easily changed using any text editor. They don't need to be changed, though, unless you re- group or add commands within the function blocks. But -- --> IMPORTANT NOTE: Any changes you make in your .MNU or .ANS/.ASC menus should also be made in your .PDM files. VBBS 6.12 Documentation -- 7-5 Creating your own .MNU menus is simple enough: after making backups of the original menu files (just in case), use your favorite drawing program (or even a text editor capable of handling "extended ASCII" characters, although this is a LOT more work) to make an ASCII menu file. To add the color changes you want, pull the file into the VBBS FSE and use heart codes to add color (as described earlier). ╔═╗ Menus are a great means of customizing your BBS. They're ╚═╝ also the primary method by which a user interacts with your BBS, so you want to design menus that are as func- tional as possible. Please note that complete script/ function block/menu/pdm packages emulating the look and feel of several other bbs softwares have been developed. The most notable of these is MVMEN by David Bell with emulations of WWIV, Remote Access, WildCat, Renegade, and others, in addition to multi-language VBBS modules. Function Blocks ═══════════════ At the heart of VBBS' command structure is the FUNCTION BLOCK, which is in turn represented by a menu. A function block is an easy-to-modify ASCII file which allows the sysop to define every single function of any menu -- what each key does, whether it is calling an internal function, an external VSCRIPT, external .EXE file (shrinking or not shrinking VBBS out of memory as de- sired), or calling another function block. Creating and editing function blocks may be done with any ASCII text editor; the resulting files should be placed in the VBBS \V or \VSCRIPT directory you have set up in VCONFIG. For example, for your FILES.FB, the first line of the function block might now read FILE1. This would instruct VBBS to display a menu file called FILE1.MNU, FILE1.ANS, FILE1.ASC, or FILE1.PDM (depending on which menuing scheme you're using and the user's default display setting). Similarly, your START.FB might call up the MAIN.xxx menu file, while your SYSOP.FB might call up the SYSOP1.xxx menu file. The second line holds the letter designators of any topic areas that "go with" the function block. For example, if you VBBS 6.12 Documentation -- 7-6 have message topic areas A, B, C, and D, the second line of your START.FB should read ABCD Otherwise, your users would only see ONE topic area; the "A" topic that came preconfigured as a default. Many new sysops for- get to add these other topic designators in; it's not difficult to overlook this, even though it IS crucial. Each subsequent line of a function block enables a "hot- key" to perform a particular command or function. Lines in the "body" of a function block MUST follow this particular format and appear in strict columns: k xxx y cccccccccccc An explanation is given below. Part Column(s) Explanation ───── ───────── ──────────────────────────────────────────── k 1 The letter or symbol serving as the hot-key xxx 3-5 The minimum SL needed to access the function (must be three digits, like "050" or "007") y 7 The command type (a digit 0-5; more on that below) cccccc 9+ The name of the routine/script/.EXE command line, etc.; this section is of variable length, depending on what you're trying to do. The "y" in the command line represents a digit from 0 through 5 that tells VBBS how to execute the command, according to the following list: Digit Command-type Description ───── ─────────────────────────────────────────────────────── 0 Null (no operation) 1 Internal command (like SENDEMAIL) 2 Script 3 DOS function (don't shrink VBBS out of memory) 4 DOS function (shrink VBBS out of memory) 5 Transfer control to a different function block A sample function block to handle E-mail might look some- thing like this (without the parts inside angle-brackets): EMAIL <name of menu file> <no database attached; E-mail's automatic> e 001 1 sendemail m 001 1 reademailto f 001 1 feedback s 001 1 reademailsent q 000 5 start <on quitting, return to START.FB> VBBS 6.12 Documentation -- 7-7 The Default START.FB ──────────────────── VBBS could easily have been distributed with a blank menu; instead, a default START.FB is included which reflects the con- figuration of the software on the author's BBS, "Virtual Techno- logies". Note the columnation at the beginning of each line and the topic-area designator on the second line. Other points of interest include: 1) the 255 SL required to transfer control to the SYSOP.FB function block; 2) the VBBS-AUX commands that shrink the BBS out of memory to execute the associated program; and 3) the nonalphabetic characters used as hot-keys. MAIN A $ 001 1 choosetopic > 001 1 nextbase < 001 1 prevbase c 001 1 selectbase j 001 1 setquickscan s 001 1 scanmsg n 001 1 readnewmsg r 001 1 readseqmsg p 001 1 post e 001 1 sendemail y 001 1 reademailfrom m 001 1 reademailto q 001 1 quickmail f 001 1 feedback o 001 1 door z 001 4 vbbs-aux %1 telecon d 001 1 account l 001 1 pagesysop t 001 5 files b 001 4 vbbs-aux %1 textfiles k 001 1 listcallers u 001 4 vbbs-aux %1 listusers a 001 1 autopost v 001 4 vbbs-aux %1 vote i 001 1 sysinfo w 001 1 who x 001 4 vbbs-aux %1 listnet * 255 5 sysop g 000 1 logoffyn Making changes is as simple as pulling the START.FB file into a text editor (even the VBBS FSE, from WITHIN the board!) and adding in the desired function(s). For example, you might add in the following line to invoke a script that shows a user his/her credit total: # 001 2 crcheck Notice that all this is presented in lower-case; function blocks are NOT case-sensitive, so the number of commands you may have VBBS 6.12 Documentation -- 7-8 is limited to 26 letters + 10 digits + however many punctuation and nonalphabetic characters you can come up with (of course, if any FB ever gets that big, you'll probably want to split it into smaller chunks anyway). ╔═╗ If you start breaking your function blocks into smaller ╚═╝ pieces, it's important to choose letter commands -- "hot keys" -- in such a way that commands will be consistent across menus. For example, if you have the [M] key set to jump to the Message Menu in one function block, try to make it do the same thing in ALL function blocks. This may not be easy, but your users will appreciate not having to learn a different set of hotkeys at each menu. The Default FILES.FB and SYSOP.FB ───────────────────────────────── There are two other default function blocks: FILES.FB, which governs the file transfer section(s), and SYSOP.FB, which contains the commands for the sysop function block. These func- tion blocks are shown below: FILE1 SYSOP1 F g 000 1 logoffyn m 255 1 readallemail m 001 1 dlmasterlist e 255 1 editfile u 001 1 remoteupload u 255 1 useredit d 001 1 downloadfile s 255 4 vbbs-aux %1 security r 001 1 reviewfile v 255 1 validate c 001 1 selectbase c 255 1 cleanup j 001 1 setnewfilesscan q 000 5 start l 001 1 listfiles n 001 1 newfiles s 001 1 searchall b 001 1 batchdl f 001 1 findfiles > 001 1 nextbase < 001 1 prevbase p 001 1 topdownloads y 001 1 ratio z 255 1 sysopupload x 255 1 reviewuploads q 000 5 start One change to FILES.FB you might want to try right off the bat -- if you have more than one files area and want to fiddle with the function blocks (and if Roland hasn't added it in as a de- fault command yet) -- is to add in this line: $ 001 1 choosetopic No compilation is necessary ... just save it, and the the [$] command to move between files topic areas is enabled, just like VBBS 6.12 Documentation -- 7-9 in the message bases! Make sure, though, that you add the com- mand in your menus so your users can take advantage of it. Rearranging the commands in function blocks isn't that difficult -- it's just a matter of making sure you don't leave out any commands. For example, I have separate function blocks for the Main Menu (12 whole commands!), E-mail, transfers, and subsystems, coupled with the ability to jump between FBs with one keystroke. Of course, my menu structure is quite different from the default setup -- but that's the beauty of VBBS. It didn't blink an eye when I installed the changes! One caveat, however: your main function block MUST be called START.FB. It is the function block that takes over when the START.V script finishes running. Scripts and Mods ════════════════ As stated earlier, the term "scripts" refers to programs written using VSCRIPT and compiled using the program VCOM.EXE; "mods" refers to source-code modifications (just a reminder). The VSCRIPT language is one of the most powerful features of VBBS (if not THE most powerful). It's a small programming language, somewhat similar to the REXX script language, that incorporates many of VBBS' functions into single command state- ments (with or without command-line arguments). All it takes is your favorite ASCII text editor or word processor and some familiarity with the VSCRIPT language (that's a separate part of the documentation; see Chapter 10 for details), and you can be customizing your BBS via scripts in no time. As an example, let's take the script mentioned earlier that allows users to check their credits. It consists of only three lines: tr tr "You currently have " $credits " credits." tr Save this file in your \V or \VSCRIPT directory (as you have it configured in VCONFIG) under the name CRCHECK.V (to maximize efficiency, you might want to keep a copy of VCOM.EXE in this directory as well). Compile the script: VCOM CRCHECK.V and you will see two NEW files in the directory: CRCHECK.COD and CRCHECK.LIT. These are the files VBBS will look for when you execute the script from the function block in which it's placed. There are literally dozens, if not hundreds, of VSCRIPT- based applications available through VirtualNET (more about that later). Some enterprising programmers have created casino games, alternate mail and voting routines, scripts to welcome new users VBBS 6.12 Documentation -- 7-10 and take them on a tour of the BBS, show user information ... it's difficult to describe the variety of scripts that have been written by sysops and users alike! VBBS may also be modified through direct changes to the source code, a process known as "source modding" or simply "mod- ding". This DOES require that you have a copy of either Micro- soft's QuickBASIC compiler (version 4.5 or later). The "QBASIC" that comes with MS-DOS is NOT sufficient for this purpose. VBBS employs a mixed programming environment using assem- bly-language routines for fast COM port and program I/O, while using QuickBASIC as an affordable and easy-to-modify environment. This is in sharp contrast to many other BBS softwares, which re- quire a knowledge of Pascal or C and their associated compilers. It should be noted here, however, that in order to keep the source-code files from being too large, there are very few com- ments in the default program; this can make for an -- <ahem!> -- INTERESTING time when you're looking for a particular routine or section of the code. Just thought we'd let you know in ad- vance ...! :-) ╔═╗ Some helpful hints to make your source modding easier: ╚═╝ 1) Make backup copies of the existing source code. It might save you truckloads of grief later. 2) Print out the source code (make a pot of coffee or something while you do ... it takes a while) and read through it BEFORE you start modding. The files are simply too complex to try to keep up with on a screen- by-screen basis. Highlighting's much easier, too; my source-code printout has so much red ink on it that it looks like a bad high-school English paper. 3) Make sure you're thoroughly familiar with the functions and commands of VBBS; this will make it easier to spot their associated source routines. --> IMPORTANT NOTE: Access to the QB4.5 DOS source code is governed by a specific licensing agreement. You may not possess any portion of the source without having obtained a license to do so from the VBBS author, and in no case shall more than 100 lines of VBBS code be con- tained within a published modification at any time. ▒▒ OS/2 Version : Please note that source code is not made available for source modding. Full scripting is possible. VBBS 6.12 Documentation -- 7-11 Scripts and Mods on VirtualNET ────────────────────────────── Once your BBS is a VirtualNET node (more on that in a bit), there are many message subs dedicated to VBBS scripts and mods. Two main subs are: VBBS Script Technical Support VBBS Source Technical Support The "VBBS Script Technical Support" sub is for the discus- sion of scripts and mods -- questions, troubleshooting, and the like. The "Virtual ModNET" is EXCLUSIVELY for the posting of script/mod code -- no discussion. System Taglines ═══════════════ Many sysops whose BBSs are part of VirtualNET like to "personalize" posts originating from their system by adding a system tagline to the posts. System taglines are optional; if they are used, however, they must follow several guidelines: 1) They must include the name of the BBS, its geo- graphic location, VirtualNET node number, and version of VBBS being used; 2) They must be 3 lines or less AND 300 bytes or less (i.e., a 3-line, 350-byte tagline is NOT acceptable); 3) They must be colorized using ONLY heart-code ANSI (no "raw" ANSI allowed). Creating a system tagline is similar to creating a new menu; you make and save an ASCII version of the tagline, then bring it into the VBBS FSE to colorize it with heart codes. Since any experimental color changes are also saved with the tagline, it's usually a good idea to use your ASCII text edi- tor to delete any unnecessary color changes after you've got your tagline looking the way you want it. Taglines reside in your \TXT directory under the name(s) TAGLINE.xxx, where "xxx" is a number from 1 to 999. It should be noted that single- or double-digit extensions to these files should be just that, i.e., TAGLINE.1 or TAGLINE.22, and not TAGLINE.001 or TAGLINE.022. ╔═╗ A word or two on system taglines: they should be as dis- ╚═╝ tinctive as possible without being gaudy or distracting from the body of the message. "Eyesore" taglines are sometimes the butt of jokes on VirtualNET. In addition, some sysops try to cram every bit of information they VBBS 6.12 Documentation -- 7-12 can about their systems into their taglines; this is frequently viewed as being distracting, and in general, a "less-is-more" approach is best advised. If you want to advertise your huge file base or the 42 game doors your system currently has, it's usually better to make a BBS ad for the "BBS Advertisements" sub instead of trying to cram this information into your tagline. R.I.P. Remote Imaging Protocol GUI Interface ════════════════════════════════════════════ VBBS is now compatible with R.I.P. graphic standards. RipTerm is an optional mouse-driven terminal program which interfaces with VBBS. R.I.P. supports user's-end VGA graphics (sorry, no VGA locally -- the "overhead" local VGA would intro- duce would be of truly epic proportions) and is icon-driven. As of this writing, a number of communication programs now support R.I.P. graphics. Details on R.I.P.may be found in the documentation that ac- companies the RipTerm Program. Adding R.I.P screens is yet another way you can customize your VBBS installation, and the early reviews are enthusiastic, to say the least! As you can see, there are quite a few ways you can cus- tomize your VBBS to get exactly the "look-and-feel" you want. It's pretty much a case of you being limited only by your imagi- nation. You can make the graphics, menus, and command structure as simple or complex as you want them. Just keep in mind that when you make changes to your user interface, it should be to make your users' lives easier, NOT to push everything to the max for the sake of doing it.